<!DOCTYPE HTML>
<html lang="en">
	<head>
		<meta charset="utf-8">
		<title>The Download Manager - The Zinc Plugin</title>
		
		
		<!-- This will all be replaced on the live site -->
		<link rel="stylesheet" href="http://dojotoolkit.org/css/site.css" type="text/css" media="all" />
		<script src="http://ajax.googleapis.com/ajax/libs/dojo/1.6/dojo/dojo.xd.js" type="text/javascript"></script>
		<link rel="stylesheet" href="http://dojotoolkit.org/documentation/tutorials/1.7/resources/style/style.css" media="screen">
		<link href="http://alexgorbatchev.com/pub/sh/current/styles/shCoreDefault.css" rel="stylesheet" type="text/css" />
		<script src="http://alexgorbatchev.com/pub/sh/current/scripts/shCore.js" type="text/javascript"></script>
		<script src="http://alexgorbatchev.com/pub/sh/current/scripts/shBrushJScript.js" type="text/javascript"></script>
		<script src="http://alexgorbatchev.com/pub/sh/current/scripts/shBrushXml.js" type="text/javascript"></script>
		<script src="http://alexgorbatchev.com/pub/sh/current/scripts/shBrushCss.js" type="text/javascript"></script>
		<!-- Don't add anything here. This will be replaced on the live site. -->
		<script>
			dojo.ready(function(){
				SyntaxHighlighter.all();
			});
		</script>
	</head>
	<body class="claro">
		<div id="page" class="docPage">
			<div id="header">
    			<div class="container">
        			<span id="logo"><a href="http://dojotoolkit.org" title="Homepage"><img src="http://dojotoolkit.org/images/logo.png" alt="Dojo Toolkit" /></a></span>
    			</div>
			</div>
			<div id="main">
				<div id="content" class="innerBox">
					<div class="pageTitleContainer">
						<h1>Documentation</h1>
						<ul class="subnav">
							<li><a href="http://dojotoolkit.org/documentation/"><span>Tutorials</span></a></li>
							<li><a href="http://dojotoolkit.org/reference-guide/"><span>Reference Guide</span></a></li>
							<li><a href="http://dojotoolkit.org/api/"><span>API Documentation</span></a></li>
						</ul>
					</div>
					<div style="clear:left;" >
						<div class="container" style="margin-bottom:50px; width:960px">
							<div class="unit size2of3 firstUnit">
								<!-- BEGIN YOUR TUTORIAL HERE -->
								<div class="tutIntro">
									<img src="images/preview.jpg" class="tut_preview" /><!-- Feel free to use youw own 200x200 image. Must be royalty free or similar license -->
									<div class="introContainer">
										<h2>Loading data into zinc with the Download Manager</h2>
										<p class="summary">Required. In this tutorial you will learn how to load data into the zinc plugin by using the download manager.</p>
										<ul>
											<li><span>Difficulty:</span> Beginner <!-- Beginner/Intermediate/Expert --></li>
											<li><span>Zinc Plugin Version:</span> 0.7 <!-- The _single_ version of dojo this is being written for. --></li>
										</ul>
									</div>
								</div>
								<h3>Getting Started</h3>
								<p>Give some background here explaining why what the user is going to learn is important.</p>
								<p>The following code sample shows the <code>zincPluginReady()</code> callback function expanded to include the definition of a node and element file to load into zinc. A download manger is created and tasked with loading those two files into memory.</p>
<!-- Only set html-script to true if you actually have HTML and JS mixed. Also you must indent this way or else things get really whacky. -->
<pre class="brush: js; html-script: false;">function zincPluginReady() {
	// the zinc plugin is ready, so we can start using it.
	console.log("The zinc plugin is now ready to go!");
	// grab a handle to the plugin object
	var plugin = document.getElementById("zincPlugin");
	/* create a download manager for reading input files */
	var downloadManager = plugin.createDownloadManager();
	/* add in URIs for downloadManager to read files from.
		In this case files from the local directories. Each item stores
		a block of memory for each file. */
	var nodesItem = downloadManager.addURI("../resources/cube.exnode");
	var elementsItem = downloadManager.addURI("../resources/cube.exelem");
	/* add in a completion callback function once the download manager has 
		 finish downloading and put the files into memory. In this case,
		 the function returned by the getCubeDownloadCompleteFunction() will
		 be called once download is finished. We wrap the callback function this
		 way to provide scope to the arguments of the callback function.
		 */
	downloadManager.addCompletionCallback(
		getCubeDownloadCompleteFunction(plugin, nodesItem, elementsItem));
}</pre>
	<p>In the following code sample, we define a function which returns the callback function used as the completion callback in the above code. This approach is used to preserve the scope of the arguments to the function.</p>
	<p>FIXME: is this a good enough explanation of why things are done this way? does it matter?</p>
<pre class="brush: js; html-script: false;">function getCubeDownloadCompleteFunction(pluginIn, nodesItemIn, elementsItemIn) {
	console.log("getting the cube download complete callback function.");
	var zincPlugin = pluginIn;
	var nodesItem = nodesItemIn;
	var elementsItem = elementsItemIn;

	// this is the actual function that will be called upon completion of the downloads
	return function() {
		// get a handle to the default root region
		var rootRegion = zincPlugin.context.getDefaultRegion();
		// create a stream information object which will be used to define the data to read 
		var streamInformation = rootRegion.createStreamInformation();
		// and add the node and element items to the stream information
		streamInformation.createResourceDownloadItem(nodesItem);
		streamInformation.createResourceDownloadItem(elementsItem);
		// Now we can load the mesh from the memory stream.
		rootRegion.read(streamInformation);
		
		// if successful we should now be able to get the cube region just loaded.
		var cubeRegion = rootRegion.findSubregionAtPath("cube");
		if (cubeRegion) {
			alert("The cube region successfully loaded with");
			// FIXME: is there a better way to check for success?
		} else {
			alert("Something went horribly wrong loading the cube region?");
		}
	}
}</pre>
								<p>Code samples are great but we want to show them that the code example actually works, so that's where the view demo button comes in. Note, it's ok to have a few code samples strung together that lead up to a single demo.</p>
								<a class="demoBtn demo" href="demo/demo.html">View Demo</a>

								<p>Explain to the user what the above code does when run and why it does it. While your demo should be well documented it's nice to be able to read the author's view of what the demo does. For example, this code sample has this description after it:</p>
								<h3>What else to show?</h3>
								<ul>
									<li>other callback methods?</li>
									<li>better way to check that things work?</li>
									<li>talk about any restrictions on where the data can come from?</li>
									<li>multiple download managers?</li>
								</ul>
							<h3>Conclusion</h3>
							<p>Now you know how to download and load files into the zinc plugin...</p>
						</div>
						<div class="sidebar unit size1of3">
							<div class="container">
								<div class="sidebarSection">
									<h4>About the Author</h4>
									<div class="authorInfo">
										<img src="images/avatar.jpg" class="avatar" />
										<p>
											Andre is awesome at the <a href="http://www.abi.auckland.ac.nz">The Auckland Bioengineering Institute</a>
											<!-- Your avatar should be 100x100. Keep your bio to a couple of lines and provide a link to your website -->
										</p>
									</div>
								</div>
							</div>
						</div>
					</div>
				</div>
			</div>
		</div>
		<br style="clear:both;" />
		<div id="main">
			<div id="content" class="innerBox">
				<div id="foot">
					<div class="innerBox">
						<span class="redundant">&copy;</span> <a href="http://dojofoundation.org">The Dojo Foundation</a>, All Rights Reserved.&nbsp;&nbsp;&nbsp;<a href="http://dojotoolkit.org/license/">License Information</a>
					</div>
				</div>
			</div>
		</div>
	</body>
</html>